home *** CD-ROM | disk | FTP | other *** search
/ Australian Personal Computer 1998 July / apc37.iso / netkit / mac / dcomet / dcomet.hqx / Documents / 5. AppleScript < prev    next >
Encoding:
Text File  |  1998-01-29  |  10.0 KB  |  298 lines
  1.  
  2.  
  3.                              4. AppleScript
  4.  
  5. _____________________________________________________________________________
  6.  
  7.             dataComet documentation (Rev. 8/26/97):
  8.             Copyright 1996 databeast, Inc. All Rights Reserved.
  9.  
  10.    This document has information on (select and use "Find..." to go to the section):
  11.  
  12.          Using AppleScript with dataComet
  13.             Sample AppleScript Copy and Paste
  14.          dataComet's AppleScript Suites
  15.             Required Suite 
  16.             URL Suite 
  17.             dataComet Custom Suite 
  18.             Mandarin Suite 
  19.          "status" report format
  20.  
  21.       ___________________________________________________
  22.  
  23.          Using AppleScript with dataComet
  24.       ___________________________________________________
  25.  
  26.    dataComet supports AppleScript commands which allow the user to control dataComet through scripts.  All dataComet macro functions are accessible through the "execute" event, which submits a macro string to dataComet for execution by the frontmost window.
  27.  
  28.    Currently AppleScript recording is not supported by dataComet.  You can, however, record a dataComet macro using "Record macro..." and then use the results in an execute command.  Note that '\' characters in the macro commands must be doubled ("\\") in order to prevent your AppleScript Script Editor application from interpreting them as special characters.
  29.  
  30.    As of the 4.43B4 version, some limitations apply on the use of the "copy" and "paste" commands in AppleScript when dataComet is in the background.  A sample script appears below to show how to use the copy and paste commands when controlling dataComet while it is in the background.
  31.  
  32.             
  33.       ___________________________________________________
  34.  
  35.             Sample AppleScript Copy and Paste
  36.       ___________________________________________________
  37.  
  38.          global copyresult
  39.  
  40.          set copyresult to ""
  41.  
  42.          tell application "dataComet"
  43.  
  44.              -- activate
  45.              -- Adding an "activate" command brings dataComet to the front 
  46.              -- and will guarantee that copy and paste work "naturally."
  47.              -- If you don't add it, the Clipboard will not be updated in your 
  48.              -- foreground application, and you need to copy "the result"
  49.              -- (as below) of the copy to update the clipboard correctly
  50.              
  51.              execute "!WSYourWindowName\\000!Ce"
  52.              -- Select a window by name; 
  53.              --    "!Ce" guarantees the emulator is in front, 
  54.              --         rather than the session's .edit window.
  55.              
  56.              execute "!S\\000!T\\000!U\\003!V\\000"
  57.              -- Select the first 3 lines in the emulator screen.
  58.              
  59.              copy
  60.  
  61.          end tell
  62.  
  63.          set copyresult to the result
  64.          -- copy the result of the dataComet copy; 
  65.          --    NOTE:  this must be immediately after the "copy" command in 
  66.          --    the "tell" statement to work correctly in the background!
  67.  
  68.          doedit(copyresult)
  69.  
  70.          return
  71.  
  72.          -- paste text into a new Scriptable Text Editor window
  73.  
  74.          on doedit(edittext)
  75.              tell application "Scriptable Text Editor"
  76.                  activate
  77.                  set the clipboard to edittext
  78.                  make window
  79.                  paste
  80.              end tell
  81.          end doedit
  82.             
  83.       ___________________________________________________
  84.  
  85.    The AppleScript dataComet "copy" command now waits for up to 45 seconds for dataComet macros executing in the frontmost session to be completed before copying the window selection to try to guarantee that select/copy macro scripts will work smoothly.  NOTE that during this wait all applications on your Macintosh will have to wait for the loop to complete; if you're using a complicated macro to display and select text, it's best to check whether the "status" of a session contains "Executing" before performing a copy; this way you can be absolutely certain that complex selection macros will copy the selection you really want.  
  86.  
  87.    More sample script snippets which might be useful...
  88.  
  89.       ___________________________________________________
  90.  
  91.          -- note that some Applescript variables may need to be coerced to "text";
  92.          -- otherwise it will abort the script noting "incorrect data type" 
  93.  
  94.             send (thisorderedlist as text)
  95.  
  96.          -- This is a sample prompt line.  
  97.          -- Note that in an "execute" command you need to use 
  98.          -- a "!!" to sends a "!" to the host.
  99.  
  100.          execute "!qzThis is a 25th line prompt!!!qz"
  101.  
  102.          -- This clears the prompt line.
  103.  
  104.          execute "!qz!qz"
  105.  
  106.          -- uploadtext(copyresult, "uploadtext.txt")
  107.          -- uploads an  AppleScript text object via a UNIX command.
  108.          -- Note that 8-bit characters won't pass unless the host 
  109.          -- is set to read them (see "UNIX connections" in "1. Emulators").
  110.  
  111.          on uploadtext(thetext, filename)
  112.              tell application "dataComet4.43B6"
  113.                  send "cat >" & filename & " <<'###EOF###'" & return
  114.                  send thetext
  115.                  send return & "'###EOF###'" & return
  116.              end tell
  117.          end cat
  118.  
  119.  
  120.       ___________________________________________________
  121.  
  122.  
  123.       ___________________________________________________
  124.  
  125.          dataComet's AppleScript Suites
  126.       ___________________________________________________
  127.  
  128.          _____________________________________________
  129.  
  130.             Required Suite 
  131.  
  132.             Events that every application should support
  133.  
  134.          _____________________________________________
  135.  
  136.             open: Open the specified object(s)
  137.  
  138.                open  alias -- list of objects to open
  139.  
  140.             print: Print the specified object(s)
  141.  
  142.                print  alias -- list of objects to print
  143.  
  144.             quit: Quit application
  145.  
  146.                quit
  147.  
  148.             run: Sent to an application when it is double-clicked
  149.  
  150.                run
  151.  
  152.          _____________________________________________
  153.  
  154.             URL Suite 
  155.  
  156.             Standard Suite for Uniform Resource Locators
  157.  
  158.          _____________________________________________
  159.  
  160.             geturl: opens a Telnet connection specified by a URL
  161.  
  162.                geturl  string -- a Telnet URL
  163.                Result:  small integer -- result code
  164.  
  165.          _____________________________________________
  166.  
  167.             dataComet Custom Suite 
  168.  
  169.             Suite of AppleEvents for interfacing to dataComet
  170.  
  171.          _____________________________________________
  172.  
  173.             status: returns status for the front window
  174.  
  175.                status
  176.                Result:  string -- text description of status
  177.  
  178.             send: sends text to the topmost window
  179.  
  180.                send string -- text to send
  181.                Result:  small integer -- result code
  182.  
  183.             execute: executes a string as a dataComet macro
  184.  
  185.                execute string -- a dataComet macro
  186.                Result:  small integer -- result code
  187.  
  188.             cut: cuts the selection in the front window
  189.  
  190.                cut
  191.                Result:  string -- the cut text
  192.  
  193.             copy: copies the selection in the front window
  194.  
  195.                copy string -- optional string overrides selection 
  196.                Result:  string -- copied text
  197.  
  198.             paste: pastes into the front window at the cursor position
  199.  
  200.                paste string -- optional string sets clipboard before paste
  201.                Result:  small integer -- result code
  202.  
  203.          _____________________________________________
  204.  
  205.             Mandarin Suite 
  206.  
  207.             provides compatibility with Cornell's "Mandarin" LaunchPad
  208.  
  209.          _____________________________________________
  210.  
  211.             sleep: Close sleep-able connections and bring the caller back 
  212.                to the foreground.
  213.  
  214.                sleep
  215.  
  216.       ___________________________________________________
  217.  
  218.  
  219.       ___________________________________________________
  220.  
  221.          "status" report format
  222.       ___________________________________________________
  223.  
  224.  
  225.    The status inquiry returns a string containing a list of tab-delimited strings which can help in monitoring the status of the frontmost session.  The string may contain the following names and status indications:  "WindowName LineCount CharCount SessionType TermType NewData ConnectionStatus 3270Status MacroStatus".  You can use the MacroStatus returned by the "status" call to synchronize scripts by using a '!Z' or '!z' macro at the end of an "execute" call to guarantee that the host has sent an indication that its output is complete (this is application-dependent, since you must rely how the host application draws its screens).
  226.  
  227. E.g., you might receive the following status reports:
  228.  
  229.          "\"fedworld.gov\"    857    68560     Telnet    ANSI.SYS    NewData    Closed"
  230.  
  231.    or
  232.  
  233.          "\"Scratch Pad\"    22    186    EditOnly".
  234.  
  235.  
  236.          _____________________________________________
  237.  
  238.  
  239.             WindowName:           Window name:  
  240.  
  241.                ".edit" will be appended if a session's .edit window is in front.
  242.  
  243.             LineCount:            Count of lines in window
  244.  
  245.             CharCount:            Count of characters in window
  246.  
  247.             SessionType:          Session type: 
  248.  
  249.                "EditOnly"
  250.                "Telnet"
  251.                "Serial"
  252.  
  253.             TermType:             Session terminal type:
  254.  
  255.                "VT100"
  256.                "VT102"
  257.                "VT220"
  258.                "H19"
  259.                "ANSI.SYS"
  260.                "IBM-3278-"
  261.  
  262.             NewData:              Session has received new data:
  263.  
  264.                ""
  265.                "NoData"
  266.                "NewData"
  267.  
  268.             ConnectionStatus:     Session connection status:
  269.  
  270.                ""
  271.                "Opening"
  272.                "Connected"
  273.                "Closing"
  274.                "Closed"
  275.  
  276.            3270Status:            Session status for IBM 3270 session:
  277.  
  278.                ""
  279.                "Running"
  280.                "MORE"
  281.                "VM Read"
  282.                "CP Read",
  283.                "Holding"
  284.  
  285.             MacroStatus:          Macro execution status
  286.  
  287.                   "Waiting"
  288.                   "Executing"
  289.  
  290.          _____________________________________________
  291.  
  292.  
  293.       ___________________________________________________
  294.  
  295.  
  296. _____________________________________________________________________________
  297.  
  298.